# Creating a new Custom Field Value

Creates a new value for the specified custom field. Creating a value can also override existing values,
effectively making this an update request as well.
When creating new [single or multi choice values](/tag/Custom-Field-Choices) that
override existing values, note that new values are not *added* to existing values, but instead *replace* existing values.
Additionally, every new value has a unique, new ID.
This endpoint has its own rate limit. See the [Knowledge Base](https://knowledge.kantata.com/hc/en-us/articles/9698066628123) for more information.
**Bulk Create or Update**
This endpoint supports bulk creating or updating up to 100 objects. In the request body, set the top-level key to its plural form and place the objects in an array. Example:

```
{
  "custom_field_values": [
    {
      "subject_type": "Workspace",
      "subject_id": 123,
      "custom_field_id": 456,
      "value": "Hello world"
    },
    {
      "subject_type": "Workspace",
      "subject_id": 123,
      "custom_field_id": 789,
      "value": "Hello world"
    }
  ]
}
```
This endpoint returns structured Custom Field Value objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array
and will be indexed by ID in the `custom_field_values` top-level JSON key.
Please see our [Response Format](#section/Response-Format) section for more information.

Endpoint: POST /custom_field_values
Version: 1.0.0

## Query parameters:

  - `include` (string)
    Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`.
- `custom_field`
 (CustomField) - Retrieves the custom field the value is for. The response will include
`custom_field_id`
, which references the data in the
`custom_fields`
 top-level key.
- `external_references`
 (ExternalReference) - Includes references to external integrations for this object.
- `selected_choices`
 (CustomFieldChoice) - Retrieves the custom field choice that corresponds to the custom field value. The response will include
`selected_choice_ids`
, which references the data in the
`custom_field_choices`
 top-level key.
- `setter`
 (User) - Retrieves the user that set the custom field value. The response will include
`setter_id`
, which references the data in the
`users`
 top-level key.
- `subject`
 (polymorphic) - Retrieves the object which the custom field value is for. The response will include
`subject_ref`
, which references the data in the top-level key specified in the
`key`
 field of
`subject_ref`
. The possible objects are as follows:

* `Estimate`
* `Workspace`
 (Project)
* `WorkspaceGroup`
 (Group)
* `Resource`
* `Story`
 (Task)
* `User`
.

## Request fields (application/json):

  - `custom_field_value` (object)

  - `custom_field_value.subject_type` (string, required)
    You must specify which set of Custom Fields to return values for:
* `Estimate`
* `Story`
 (Task)
* `User`
* `Workspace`
 (Project)
* `WorkspaceGroup`
 (Group)
* `Resource`

This parameter is required.

  - `custom_field_value.subject_id` (integer, required)
    The ID of the Estimate, Project, Group, Resource, Task, or User the custom field is for.

  - `custom_field_value.custom_field_id` (integer, required)
    The ID of the Custom Field to create or update the value for.

  - `custom_field_value.value` (string, required)
    The value to create or update to for the specified custom field.
Values can be created or updated in these formats:
| Value Type | Format | Sample |
|  --- | --- | --- |
| `string` | `<text_string>` | `"foo"` |
| `date` | `<ISO_8601 Date Format>` | `"2014-02-25"` |
| `number` | `<integer_value>` | `13` |
| `currency` | `[<int_value_in_cents>, <currency_code>]` | `[998, "USD"]` |
| `single` and `multi` | `[<choice_ids>]` | `[1, 2, 4]` |

##### Note:
The `write_access` [permission setting on each custom field](https://knowledge.kantata.com/hc/en-us/articles/202924760#see)
determines the minimum permission needed to edit the value of each custom field.
* Editing
`Workspace`
 (Project),
`Resource`
, and
`Story`
 (Task) custom fields are project-specific changes,

so permissions are set at the project level:

- `project_collaboration`
- `time_logging`
- `financial`
- `project_admin`
 (default)

Most account-level permissions supercede project-level permissions. Therefore, Account Administrators
are able to edit all Project, Resource, and Task custom fields and values across the account,
regardless of project participation or `write_access` settings.
* Editing
`Estimate`
,
`WorkspaceGroup`
 (Group), and
`User`
 custom fields are account-wide changes,

so permissions are set at the account level:

- `account_collaboration`
- `project_creator`
- `project_lead`
- `reports_viewer`
- `reports_viewer_with_cost`
- `account_admin`
 (default).

## Response 200:

  - `200` (unknown)
    Custom Field Value has been created.

## Response 200 fields (application/json):

  - `count` (integer)

  - `meta` (object)

  - `meta.count` (integer)

  - `meta.page_count` (integer)

  - `meta.page_number` (integer)

  - `meta.page_size` (integer)

  - `results` (array)

  - `results.key` (string)

  - `results.id` (string)

  - `custom_field_values` (object)

  - `external_references` (object)

  - `custom_fields` (object)

  - `users` (object)

  - `custom_field_choices` (object)

  - `stories` (object)

  - `workspaces` (object)

  - `workspace_groups` (object)

## Response 400:

  - `400` (unknown)
    Bad Request

## Response 400 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 401:

  - `401` (unknown)
    Unauthorized request

## Response 401 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 403:

  - `403` (unknown)
    Forbidden request

## Response 403 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 404:

  - `404` (unknown)
    Page Not Found

## Response 404 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 422:

  - `422` (unknown)
    Unprocessable Entity

## Response 422 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 503:

  - `503` (unknown)
    Service is unavailable

## Response 503 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)